<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>21.3. cgitb — Traceback manager for CGI scripts &mdash; Python v2.6.2 documentation</title>
    <link rel="stylesheet" href="../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '2.6.2',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <link rel="search" type="application/opensearchdescription+xml"
          title="Search within Python v2.6.2 documentation"
          href="../_static/opensearch.xml"/>
    <link rel="author" title="About these documents" href="../about.html" />
    <link rel="copyright" title="Copyright" href="../copyright.html" />
    <link rel="top" title="Python v2.6.2 documentation" href="../index.html" />
    <link rel="up" title="21. Internet Protocols and Support" href="internet.html" />
    <link rel="next" title="21.4. wsgiref — WSGI Utilities and Reference Implementation" href="wsgiref.html" />
    <link rel="prev" title="21.2. cgi — Common Gateway Interface support." href="cgi.html" />
    <link rel="shortcut icon" type="image/png" href="../_static/py.png" />
 

  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="wsgiref.html" title="21.4. wsgiref — WSGI Utilities and Reference Implementation"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="cgi.html" title="21.2. cgi — Common Gateway Interface support."
             accesskey="P">previous</a> |</li>
        <li><img src="../_static/py.png" alt=""
                 style="vertical-align: middle; margin-top: -1px"/></li>
        <li><a href="../index.html">Python v2.6.2 documentation</a> &raquo;</li>

          <li><a href="index.html" >The Python Standard Library</a> &raquo;</li>
          <li><a href="internet.html" accesskey="U">21. Internet Protocols and Support</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="module-cgitb">
<h1>21.3. <tt class="xref docutils literal"><span class="pre">cgitb</span></tt> &#8212; Traceback manager for CGI scripts<a class="headerlink" href="#module-cgitb" title="Permalink to this headline">¶</a></h1>
<p>
<span class="versionmodified">New in version 2.2.</span></p>
<p id="index-215">The <tt class="xref docutils literal"><span class="pre">cgitb</span></tt> module provides a special exception handler for Python scripts.
(Its name is a bit misleading.  It was originally designed to display extensive
traceback information in HTML for CGI scripts.  It was later generalized to also
display this information in plain text.)  After this module is activated, if an
uncaught exception occurs, a detailed, formatted report will be displayed.  The
report includes a traceback showing excerpts of the source code for each level,
as well as the values of the arguments and local variables to currently running
functions, to help you debug the problem.  Optionally, you can save this
information to a file instead of sending it to the browser.</p>
<p>To enable this feature, simply add this to the top of your CGI script:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">cgitb</span>
<span class="n">cgitb</span><span class="o">.</span><span class="n">enable</span><span class="p">()</span>
</pre></div>
</div>
<p>The options to the <a title="cgitb.enable" class="reference internal" href="#cgitb.enable"><tt class="xref docutils literal"><span class="pre">enable()</span></tt></a> function control whether the report is
displayed in the browser and whether the report is logged to a file for later
analysis.</p>
<dl class="function">
<dt id="cgitb.enable">
<tt class="descclassname">cgitb.</tt><tt class="descname">enable</tt><big>(</big><span class="optional">[</span><em>display</em><span class="optional">[</span>, <em>logdir</em><span class="optional">[</span>, <em>context</em><span class="optional">[</span>, <em>format</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#cgitb.enable" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-216">This function causes the <tt class="xref docutils literal"><span class="pre">cgitb</span></tt> module to take over the interpreter&#8217;s
default handling for exceptions by setting the value of <a title="sys.excepthook" class="reference external" href="sys.html#sys.excepthook"><tt class="xref docutils literal"><span class="pre">sys.excepthook</span></tt></a>.</p>
<p>The optional argument <em>display</em> defaults to <tt class="docutils literal"><span class="pre">1</span></tt> and can be set to <tt class="docutils literal"><span class="pre">0</span></tt> to
suppress sending the traceback to the browser. If the argument <em>logdir</em> is
present, the traceback reports are written to files.  The value of <em>logdir</em>
should be a directory where these files will be placed. The optional argument
<em>context</em> is the number of lines of context to display around the current line
of source code in the traceback; this defaults to <tt class="docutils literal"><span class="pre">5</span></tt>. If the optional
argument <em>format</em> is <tt class="docutils literal"><span class="pre">&quot;html&quot;</span></tt>, the output is formatted as HTML.  Any other
value forces plain text output.  The default value is <tt class="docutils literal"><span class="pre">&quot;html&quot;</span></tt>.</p>
</dd></dl>

<dl class="function">
<dt id="cgitb.handler">
<tt class="descclassname">cgitb.</tt><tt class="descname">handler</tt><big>(</big><span class="optional">[</span><em>info</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#cgitb.handler" title="Permalink to this definition">¶</a></dt>
<dd>This function handles an exception using the default settings (that is, show a
report in the browser, but don&#8217;t log to a file). This can be used when you&#8217;ve
caught an exception and want to report it using <tt class="xref docutils literal"><span class="pre">cgitb</span></tt>.  The optional
<em>info</em> argument should be a 3-tuple containing an exception type, exception
value, and traceback object, exactly like the tuple returned by
<a title="sys.exc_info" class="reference external" href="sys.html#sys.exc_info"><tt class="xref docutils literal"><span class="pre">sys.exc_info()</span></tt></a>.  If the <em>info</em> argument is not supplied, the current
exception is obtained from <a title="sys.exc_info" class="reference external" href="sys.html#sys.exc_info"><tt class="xref docutils literal"><span class="pre">sys.exc_info()</span></tt></a>.</dd></dl>

</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h4>Previous topic</h4>
            <p class="topless"><a href="cgi.html"
                                  title="previous chapter">21.2. <tt class="docutils literal docutils literal"><span class="pre">cgi</span></tt> &#8212; Common Gateway Interface support.</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="wsgiref.html"
                                  title="next chapter">21.4. <tt class="docutils literal"><span class="pre">wsgiref</span></tt> &#8212; WSGI Utilities and Reference Implementation</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="../_sources/library/cgitb.txt"
                     rel="nofollow">Show Source</a></li>
            </ul>
          <div id="searchbox" style="display: none">
            <h3>Quick search</h3>
              <form class="search" action="../search.html" method="get">
                <input type="text" name="q" size="18" />
                <input type="submit" value="Go" />
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
              </form>
              <p class="searchtip" style="font-size: 90%">
              Enter search terms or a module, class or function name.
              </p>
          </div>
          <script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../modindex.html" title="Global Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="wsgiref.html" title="21.4. wsgiref — WSGI Utilities and Reference Implementation"
             >next</a> |</li>
        <li class="right" >
          <a href="cgi.html" title="21.2. cgi — Common Gateway Interface support."
             >previous</a> |</li>
        <li><img src="../_static/py.png" alt=""
                 style="vertical-align: middle; margin-top: -1px"/></li>
        <li><a href="../index.html">Python v2.6.2 documentation</a> &raquo;</li>

          <li><a href="index.html" >The Python Standard Library</a> &raquo;</li>
          <li><a href="internet.html" >21. Internet Protocols and Support</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
      &copy; <a href="../copyright.html">Copyright</a> 1990-2009, Python Software Foundation.
      Last updated on Apr 15, 2009.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.1.
    </div>
  </body>
</html>